#ifndef _SDB_LIST_H_
#define _SDB_LIST_H_

/* 
 * Spinneret - Semi-Structured Database Engine
 * Copyright (c) 2009 Tom Bradford <spinneretdb.org>
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a 
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included
 * in all copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
 * DEALINGS IN THE SOFTWARE.
 */

/**
 * Implements a simple dynamic list based on linked nodes of multiple
 * pointer arrays.  This method provides an acceptible tradeoff between
 * list scaling and both indexed and scanned access methods.
 * 
 * Note: These functions are NOT thread-safe.  You must manage your
 * own mutexes if you plan on safely threading a List or List-derived
 * structures.
 */

#include <stdbool.h>

#include "main/common.h"
#include "utils/mem.h"

#ifdef __cplusplus
extern "C" {
#endif // __cplusplus


#define SDB_LIST_REMOVE -1

/** Incomplete type for List instances */
typedef struct sdb_list_t sdb_list_t;

/** Function type for List iteration callbacks */
typedef sdb_status_t sdb_list_iterator_t(sdb_list_t* list, void* item, 
                                         void* context);

/** Create a List instance */
sdb_list_t* sdb_list_new(sdb_mem_t* mem);

/** Sets the cluster size that the list uses for allocation */
void sdb_list_setClusterSize(sdb_list_t* list, int clusterSize);

/** Returns the cluster size that the list uses for allocation */
int sdb_list_getClusterSize(sdb_list_t* list);

/** Appends an item to the end of the List */
void sdb_list_addItem(sdb_list_t* list, void* item);

/** Inserts an item into the list at the specified index */
void sdb_list_insertItem(sdb_list_t* list, int index, void* item);

/** Removes the specified item from the List */
void sdb_list_removeItem(sdb_list_t* list, void* item);

/** Removes the item at the specified index from the List */
void* sdb_list_removeIndex(sdb_list_t* list, int index);

/** Removes all items from the List */
void sdb_list_removeAll(sdb_list_t* list);

/** Returns the item at the specified index from the List */
void* sdb_list_getItem(sdb_list_t* list, int index);

/** Returns the index for the specified item in the List */
int sdb_list_getIndex(sdb_list_t* list, void* item);

/** Sets the item at the specified index in the List */
void* sdb_list_setItem(sdb_list_t* list, int index, void* item);

/** Replaces the oldItem with the newItem in the List */
void sdb_list_replaceItem(sdb_list_t* list, void* oldItem, void* newItem);

/** Returns the total number of items in the List */
int sdb_list_getSize(sdb_list_t* list);

/** Returns whether or not the List is empty */
bool sdb_list_isEmpty(sdb_list_t* list);

/** Iterates over the items of the List, performing a callback for each */
sdb_status_t sdb_list_iterate(sdb_list_t* list, sdb_list_iterator_t* iterator, 
                              void* context);


#ifdef __cplusplus
}
#endif // __cplusplus

#endif // _SDB_LIST_H_
